The Selenium Python Package is the official Python binding used to automate web browsers with Selenium WebDriver. It provides Python classes, methods, modules, and APIs that allow testers and developers to open browsers, navigate web pages, locate elements, enter data, click buttons, validate results, manage browser windows, handle alerts, work with frames, take screenshots, and build complete web automation frameworks.
The selenium package acts as the bridge between Python code and Selenium WebDriver. Instead of manually interacting with a browser, a tester can write Python instructions that Selenium executes against supported browsers.
Course Resource: Selenium Training | Register for Course Demo
The Selenium Python Package is a collection of Python modules and APIs that provide access to Selenium WebDriver functionality from Python. It allows a Python program to communicate with a browser and perform automated web interactions.
The package is installed through Python's package manager, pip.
pip install seleniumAfter installation, Python programs can import Selenium modules and use WebDriver to automate supported browsers.
The Selenium package provides the programming interface required to control browsers through Python. It provides the WebDriver classes and browser automation APIs needed to build Selenium scripts.
Python Program
|
v
Selenium Python Package
|
v
WebDriver API
|
v
Browser Driver / Selenium Manager
|
v
Chrome / Edge / Firefox / Safari
|
v
Web Application
The Python package exposes the WebDriver API, while WebDriver provides the browser automation interface. Modern Selenium also includes Selenium Manager, which can help with browser and driver management in many common environments.
The standard installation command is:
pip install seleniumTo upgrade Selenium:
pip install -U seleniumIt is recommended to install Selenium inside the Python environment used by the automation project.
python -c "import selenium; print(selenium.__version__)"If the command prints a Selenium version, the package is available in the active Python environment.
python --versionOn some systems:
python3 --versionUse a Python version supported by the Selenium release installed in your project.
pip --versionIf pip is correctly installed, the command displays its version and associated Python environment information.
A virtual environment keeps project dependencies isolated. This is especially useful when multiple Selenium projects require different package versions or supporting libraries.
python -m venv selenium_envselenium_env\Scripts\activatesource selenium_env/bin/activatepip install seleniumdeactivate
After installation, the Selenium package can be imported into a Python program.
import seleniumFor browser automation, the most common import is:
from selenium import webdriverThe webdriver module provides the browser WebDriver implementations.
The Selenium Python package contains several modules and submodules. Each module provides specific automation functionality.
selenium
|
+-- webdriver
| +-- chrome
| +-- firefox
| +-- edge
| +-- safari
| +-- common
| +-- support
|
+-- common
| +-- exceptions
| +-- keys
| +-- action_chains
|
+-- webauthn
The internal package structure can change between releases, so automation code should generally import public Selenium APIs rather than relying on private implementation details.
| Module | Purpose |
|---|---|
| selenium.webdriver | Creates and controls WebDriver instances |
| selenium.webdriver.common.by | Provides locator strategies |
| selenium.webdriver.common.keys | Provides keyboard keys |
| selenium.webdriver.common.action_chains | Provides advanced mouse and keyboard actions |
| selenium.webdriver.support.ui | Provides wait and UI helper classes |
| selenium.webdriver.support.expected_conditions | Provides common explicit-wait conditions |
| selenium.common.exceptions | Provides Selenium exception classes |
| selenium.webdriver.chrome.options | Chrome browser configuration |
| selenium.webdriver.firefox.options | Firefox browser configuration |
| selenium.webdriver.edge.options | Edge browser configuration |
from selenium import webdriver
driver = webdriver.Chrome()
driver.get("https://example.com")
print(driver.title)
driver.quit()
webdriver.Chrome() creates a Chrome WebDriver instance. In modern Selenium environments, Selenium Manager can assist with driver management.
from selenium import webdriver
driver = webdriver.Edge()
driver.get("https://example.com")
print(driver.title)
driver.quit()
from selenium import webdriver
driver = webdriver.Firefox()
driver.get("https://example.com")
print(driver.title)
driver.quit()
from selenium import webdriver
driver = webdriver.Safari()
driver.get("https://example.com")
print(driver.title)
driver.quit()
Browser availability and local configuration can vary depending on the operating system and test environment.
from selenium import webdriver
driver = webdriver.Chrome()
try:
driver.get("https://example.com")
print("Title:", driver.title)
finally:
driver.quit()
Import Selenium
|
v
Create WebDriver
|
v
Open Website
|
v
Perform Actions
|
v
Validate Result
|
v
Quit Browser
The webdriver module is one of the most important components of Selenium Python. It provides access to browser-specific WebDriver classes.
from selenium import webdriverExamples include:
webdriver.Chrome()
webdriver.Edge()
webdriver.Firefox()
webdriver.Safari()
The By class is used to specify how Selenium should locate an element on a web page.
from selenium.webdriver.common.by import By| Strategy | Python Syntax |
|---|---|
| ID | By.ID |
| NAME | By.NAME |
| CLASS_NAME | By.CLASS_NAME |
| TAG_NAME | By.TAG_NAME |
| LINK_TEXT | By.LINK_TEXT |
| PARTIAL_LINK_TEXT | By.PARTIAL_LINK_TEXT |
| CSS_SELECTOR | By.CSS_SELECTOR |
| XPATH | By.XPATH |
username = driver.find_element(By.ID, "username")This searches for an element whose HTML id attribute matches the supplied value.
username = driver.find_element(By.NAME, "username")
login_button = driver.find_element(
By.CSS_SELECTOR,
"button.login"
)
login_button = driver.find_element(
By.XPATH,
"//button[@id='login']"
)
find_element() is used to locate a single matching WebElement.
element = driver.find_element(
By.ID,
"username"
)
find_elements() is used when multiple matching elements are required.
links = driver.find_elements(By.TAG_NAME, "a")
for link in links:
print(link.text)
This is a common example of combining Selenium with Python loops.
Once Selenium finds an element, the returned WebElement provides methods for interacting with it.
| Method | Purpose |
|---|---|
| click() | Clicks an element |
| send_keys() | Types text or keyboard keys |
| clear() | Clears editable text |
| get_attribute() | Reads an HTML attribute |
| is_displayed() | Checks visibility |
| is_enabled() | Checks whether the element is enabled |
| is_selected() | Checks selection state |
username = driver.find_element(By.ID, "username")
username.send_keys("admin")
The send_keys() method is used to enter text or keyboard commands into an element.
login_button = driver.find_element(By.ID, "login")
login_button.click()
search_box = driver.find_element(By.NAME, "q")
search_box.clear()
search_box.send_keys("Selenium")
The Keys class provides special keyboard keys.
from selenium.webdriver.common.keys import Keys
search_box = driver.find_element(By.NAME, "q")
search_box.send_keys("Selenium")
search_box.send_keys(Keys.ENTER)
driver.get("https://example.com")
driver.back()
driver.forward()
driver.refresh()
| Method | Purpose |
|---|---|
| get() | Opens a URL |
| back() | Moves backward in browser history |
| forward() | Moves forward in browser history |
| refresh() | Refreshes the current page |
print(driver.title)
print(driver.current_url)
print(driver.page_source)
driver.title returns the current page title.driver.current_url returns the current URL.driver.page_source returns the page source.
Both methods are used for browser cleanup, but their scope is different.
driver.close()close() closes the current browser window or tab.
driver.quit()quit() ends the WebDriver session and closes the associated browser windows.
For complete test cleanup, quit() is commonly preferred when the entire WebDriver session should be terminated.
from selenium import webdriver
driver = webdriver.Chrome()
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()
This pattern helps ensure that browser cleanup happens even when an error occurs.
Selenium provides exception classes through selenium.common.exceptions.
from selenium.common.exceptions import (
NoSuchElementException,
TimeoutException
)
| Exception | Meaning |
|---|---|
| NoSuchElementException | Element could not be found |
| TimeoutException | Wait condition was not satisfied within the specified time |
| StaleElementReferenceException | Previously located element is no longer attached to the current DOM |
| ElementClickInterceptedException | Another element is preventing the click |
| ElementNotInteractableException | Element cannot currently be interacted with |
| InvalidSelectorException | Locator selector is invalid |
| WebDriverException | General WebDriver-related error |
from selenium.common.exceptions import NoSuchElementException
try:
element = driver.find_element(By.ID, "username")
element.send_keys("admin")
except NoSuchElementException:
print("Username field was not found")
Exception handling should be used carefully. It should help diagnose or recover from expected situations rather than hiding genuine test failures.
The Selenium Python package provides explicit waiting functionality through WebDriverWait.
from selenium.webdriver.support.ui import WebDriverWait
wait = WebDriverWait(driver, 10)
WebDriverWait is commonly combined with expected conditions.
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.common.by import By
wait = WebDriverWait(driver, 10)
login_button = wait.until(
EC.element_to_be_clickable((By.ID, "login"))
)
login_button.click()
presence_of_element_located()visibility_of_element_located()element_to_be_clickable()text_to_be_present_in_element()url_contains()title_contains()alert_is_present()frame_to_be_available_and_switch_to_it()
ActionChains provides advanced mouse and keyboard interactions.
from selenium.webdriver.common.action_chains import ActionChains
actions = ActionChains(driver)
actions.move_to_element(element).perform()
from selenium.webdriver.common.action_chains import ActionChains
element = driver.find_element(By.ID, "item")
ActionChains(driver).double_click(element).perform()
element = driver.find_element(By.ID, "menu")
ActionChains(driver).context_click(element).perform()
menu = driver.find_element(By.ID, "products")
ActionChains(driver).move_to_element(menu).perform()
The Select class is used for standard HTML <select> elements.
from selenium.webdriver.support.ui import Select
dropdown = driver.find_element(By.ID, "country")
select = Select(dropdown)
select.select_by_visible_text("India")
select.select_by_value("IN")
select.select_by_index(1)
alert = driver.switch_to.alert
print(alert.text)
alert.accept()
driver.switch_to.alert.dismiss()alert = driver.switch_to.alert
alert.send_keys("Test")
alert.accept()
An iframe contains another HTML document inside the current page. Selenium must switch to the frame before interacting with elements inside it.
frame = driver.find_element(By.ID, "payment-frame")
driver.switch_to.frame(frame)
driver.find_element(
By.ID,
"card_number"
).send_keys("4111111111111111")
driver.switch_to.default_content()
original_window = driver.current_window_handle
for handle in driver.window_handles:
if handle != original_window:
driver.switch_to.window(handle)
break
Python variables, loops, and Selenium window handles work together in this type of automation.
driver.save_screenshot("homepage.png")try:
driver.find_element(By.ID, "login").click()
except Exception:
driver.save_screenshot("login_failure.png")
raise
driver.get("https://example.com")
driver.add_cookie({
"name": "test_cookie",
"value": "12345"
})
print(driver.get_cookies())
driver.delete_cookie("test_cookie")
driver.delete_all_cookies()
The WebDriver API provides JavaScript execution through execute_script().
driver.execute_script(
"window.scrollTo(0, document.body.scrollHeight);"
)
element = driver.find_element(By.ID, "submit")
driver.execute_script(
"arguments[0].click();",
element
)
Browser-specific option classes can configure how a browser session starts.
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--start-maximized")
driver = webdriver.Chrome(options=options)
options = Options()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
Selenium can also connect to a remote WebDriver endpoint. This is useful for remote execution and distributed browser automation.
from selenium import webdriver
options = webdriver.ChromeOptions()
driver = webdriver.Remote(
command_executor="http://localhost:4444",
options=options
)
The exact remote endpoint and infrastructure depend on the Selenium Grid or remote execution environment being used.
The Selenium package provides browser automation APIs but does not itself act as the complete test framework. Python testing tools such as unittest or pytest can be used to organize and execute test cases.
pip install pytestfrom selenium import webdriver
def test_homepage():
driver = webdriver.Chrome()
try:
driver.get("https://example.com")
assert "Example" in driver.title
finally:
driver.quit()
import unittest
from selenium import webdriver
class HomePageTest(unittest.TestCase):
def setUp(self):
self.driver = webdriver.Chrome()
def test_homepage(self):
self.driver.get("https://example.com")
self.assertIn("Example", self.driver.title)
def tearDown(self):
self.driver.quit()
if __name__ == "__main__":
unittest.main()
Professional Selenium frameworks commonly use the Page Object Model. The Selenium package provides the browser and element APIs, while Python classes organize those APIs into reusable page objects.
from selenium.webdriver.common.by import By
class LoginPage:
def __init__(self, driver):
self.driver = driver
def enter_username(self, username):
self.driver.find_element(
By.ID, "username"
).send_keys(username)
def enter_password(self, password):
self.driver.find_element(
By.ID, "password"
).send_keys(password)
def click_login(self):
self.driver.find_element(
By.ID, "login"
).click()
Python collections can be combined with Selenium to execute the same test with multiple sets of test data.
users = [
{
"username": "admin",
"password": "admin123"
},
{
"username": "tester",
"password": "Test@123"
}
]
for user in users:
print(user["username"])
print(user["password"])
for user in users:
username = driver.find_element(By.ID, "username")
password = driver.find_element(By.ID, "password")
username.clear()
password.clear()
username.send_keys(user["username"])
password.send_keys(user["password"])
A Selenium project can maintain its Python dependencies in a requirements.txt file.
selenium
pytest
Install all listed packages with:
pip install -r requirements.txt
pip show seleniumThis command can display information such as the installed version, location, and package metadata.
pip listpip install --upgrade selenium
The installed package version can be checked through Python:
import selenium
print(selenium.__version__)
Checking the installed version is useful when troubleshooting differences between development and CI environments.
Older Selenium setups commonly required users to manually download and configure browser drivers. Modern Selenium includes Selenium Manager, which can automatically discover and manage required browser drivers in many normal configurations.
from selenium import webdriver
driver = webdriver.Chrome()
driver.get("https://example.com")
driver.quit()
If the environment requires custom browser or driver configuration, Selenium still provides ways to configure those components explicitly.
| Error/Symptom | Possible Cause | Possible Solution |
|---|---|---|
| ModuleNotFoundError: selenium | Selenium is not installed in the active Python environment | Install Selenium using pip and verify the active environment |
| Driver startup failure | Browser or driver configuration problem | Check browser installation, Selenium Manager, and environment configuration |
| NoSuchElementException | Incorrect or unavailable locator | Verify the locator and page state |
| TimeoutException | Condition was not met within timeout | Review the wait condition and timeout |
| StaleElementReferenceException | DOM changed after locating the element | Locate the element again when appropriate |
| ElementClickInterceptedException | Another element blocks the click | Wait for the correct state or investigate overlays |
If the following error appears:
ModuleNotFoundError: No module named 'selenium'Install Selenium in the Python environment being used:
python -m pip install seleniumUsing python -m pip can help ensure that pip is associated with the Python interpreter used to run the script.
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.common.keys import Keys
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
driver = webdriver.Chrome()
try:
driver.get("https://example.com")
print("Title:", driver.title)
print("URL:", driver.current_url)
search_box = WebDriverWait(driver, 10).until(
EC.visibility_of_element_located(
(By.NAME, "q")
)
)
search_box.send_keys("Selenium")
search_box.send_keys(Keys.ENTER)
finally:
driver.quit()
webdriver for browser control.By for element location.Keys for keyboard actions.WebDriverWait for explicit waits.expected_conditions for waiting conditions.send_keys() for text input.get() for navigation.title and current_url for browser information.quit() for cleanup.
selenium_project/
|
+-- tests/
| +-- test_login.py
| +-- test_search.py
| +-- test_checkout.py
|
+-- pages/
| +-- login_page.py
| +-- home_page.py
| +-- checkout_page.py
|
+-- utilities/
| +-- driver_factory.py
| +-- config.py
| +-- helpers.py
|
+-- data/
| +-- users.json
| +-- test_data.csv
|
+-- screenshots/
+-- reports/
+-- requirements.txt
+-- pytest.ini
requirements.txt or the project's dependency configuration.By for clear locator strategies.
Install Python
|
v
Create Virtual Environment
|
v
Install Selenium
|
v
Import selenium
|
v
Import webdriver
|
v
Create Browser Driver
|
v
Open Web Application
|
v
Use By Locators
|
v
Find WebElements
|
v
Perform Actions
|
v
Use Waits
|
v
Validate Results
|
v
Handle Exceptions
|
v
Create Page Objects
|
v
Build Automation Framework
| Concept | Meaning |
|---|---|
| Selenium | Overall browser automation project and ecosystem |
| selenium Python package | Python bindings used to access Selenium APIs |
| WebDriver | Browser automation interface |
| Browser Driver | Component used to communicate with a browser where required |
| Selenium Manager | Modern Selenium component that helps manage browsers and drivers |
| pytest/unittest | Test frameworks used to organize and execute tests |
The Selenium Python Package is itself a Python package containing modules and classes. When installed with pip, it becomes available to Python programs through imports.
pip install seleniumAfter installation:
from selenium import webdriver
from selenium.webdriver.common.by import By
This allows the Python program to access Selenium's browser automation functionality.
It is the official Python binding used to access Selenium WebDriver functionality from Python programs.
pip install seleniumpip install -U seleniumfrom selenium import webdriverdriver = webdriver.Chrome()The By class provides locator strategies used by Selenium to identify web elements.
driver.find_element(By.ID, "username")find_element() is used to retrieve one matching element, while find_elements() retrieves a collection of matching elements.
WebDriverWait is used to wait for a specified condition before continuing test execution.
ActionChains provides APIs for advanced mouse and keyboard interactions.
Selenium Manager is a Selenium component that can automatically manage browser and driver setup in many common environments.
The Selenium package provides browser automation APIs. Test execution and organization can be handled using frameworks such as pytest or unittest.
A virtual environment isolates project dependencies and reduces conflicts between different Python projects.
import selenium
print(selenium.__version__)
driver.quit()
| Requirement | Python/Selenium Code |
|---|---|
| Install Selenium | pip install selenium |
| Upgrade Selenium | pip install -U selenium |
| Import Selenium | import selenium |
| Import WebDriver | from selenium import webdriver |
| Import By | from selenium.webdriver.common.by import By |
| Chrome | webdriver.Chrome() |
| Edge | webdriver.Edge() |
| Firefox | webdriver.Firefox() |
| Open URL | driver.get(url) |
| Find Element | driver.find_element() |
| Find Multiple Elements | driver.find_elements() |
| Click | element.click() |
| Enter Text | element.send_keys() |
| Clear Text | element.clear() |
| Page Title | driver.title |
| Current URL | driver.current_url |
| Back | driver.back() |
| Forward | driver.forward() |
| Refresh | driver.refresh() |
| Close Current Window | driver.close() |
| Quit Session | driver.quit() |
| Screenshot | driver.save_screenshot() |
| Wait | WebDriverWait() |
| Keyboard | Keys.ENTER |
| Advanced Actions | ActionChains() |
| Dropdown | Select() |
| Alert | driver.switch_to.alert |
| Frame | driver.switch_to.frame() |
| JavaScript | driver.execute_script() |
Create a Python Selenium script that performs the following activities:
By.ID.send_keys().
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
driver = webdriver.Chrome()
try:
driver.get("https://example.com/login")
username = WebDriverWait(driver, 10).until(
EC.visibility_of_element_located(
(By.ID, "username")
)
)
password = driver.find_element(By.ID, "password")
login_button = driver.find_element(By.ID, "login")
username.send_keys("admin")
password.send_keys("admin123")
login_button.click()
print("Login action completed")
finally:
driver.quit()
The IDs in this example are illustrative. In a real application, inspect the page HTML and use the actual locators.
The Selenium Python Package is the foundation for using Selenium WebDriver with Python. It provides the APIs required to create browser sessions, navigate websites, locate web elements, perform user-like interactions, manage waits, handle browser features, capture screenshots, process exceptions, and build maintainable automation frameworks.
The most important areas to learn are webdriver, By, WebElement methods, Keys, ActionChains, WebDriverWait, expected conditions, Select, browser options, exceptions, alerts, frames, windows, cookies, screenshots, JavaScript execution, pytest/unittest integration, and Page Object Model.
Once these concepts are understood, a learner can progress from basic Selenium scripts to complete Python-based automation frameworks used for functional testing, regression testing, smoke testing, data-driven testing, and CI/CD automation.
Selenium Training: Selenium Training Course
Register for Course Demo: Register for Selenium Course Demo
Official Selenium Documentation: Selenium Documentation
Official Selenium Python API: Selenium Python API Reference
